import Doc from '~/components/layout/docs'
import Snippet from '~/components/snippet'
import Caption from '~/components/text/caption'
import Note from '~/components/text/note'
import Card from '~/components/card'
import { Image } from '~/components/media'
import { InlineCode } from '~/components/text/code'

export const meta = {
  title: 'Custom Domains',
  description: 'How to add and use a custom domain with your project.',
  editUrl: 'pages/docs/v2/custom-domains.mdx',
  lastEdited: '2020-02-13T19:57:43.000Z'
}

By default, all deployments are assigned a `.now.sh` suffixed domain.

This domain can be replaced with a **Custom Domain** of your choice. This Custom Domain can be purchased with ZEIT or a third-party.

In this document, adding a domain to your ZEIT Now [projects](/docs/v2/platform/projects/) is explained in detail.

## Adding a Domain

If you don't own a domain yet, you can [purchase it with ZEIT](https://zeit.co/domains). Then, once you own a domain, adding it to a project is very straightforward:

### Step 1: Selecting Your Project

On the [dashboard](https://zeit.co/dashboard), pick the project to which you would like to assign your domain:

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/select-project.png`}
  width={1080 / 2}
  height={320 / 2}
  shadow
/>
<Caption>Selecting the project from the ZEIT Dashboard.</Caption>

### Step 2: Navigating to Domain Settings

Once you have selected the project of your choice, click on the **Domains** item in the menubar:

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/select-domains.png`}
  width={728 / 2}
  height={274 / 2}
  shadow
/>
<Caption>Selecting the <b>Domains</b> tab from the Project Overview page.</Caption>

### Step 3: Entering Your Chosen Domain

From the **Project Domains** page, enter the domain you wish to add to the project:

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/enter-domain.png`}
  width={1350 / 2}
  height={447 / 2}
  shadow
/>
<Caption>Entering a domain for the project from the Project Domains page.</Caption>

### Step 4: Configuring the Domain

Once the domain has been added, you will be presented with different methods for configuring it, depending on whether it is an [**apex domain**](/docs/v2/platform/glossary#apex-domain) (zeit.co) or **subdomain** (docs.zeit.co).

Both domain types can be configured using the **Nameservers** method, however **apex domains** also allow for verification via the **ANAME** record, whilst **subdomains** allow for verification via the **CNAME** record.

#### Apex Domains

You can configure [apex domains](/docs/v2/platform/glossary#apex-domain) either through the **Nameservers** or **ANAME** methods.

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/configure-apex-domain.png`}
  width={1350 / 2}
  height={984 / 2}
  shadow
/>
<Caption>Instructions on configuring an <strong>apex domain</strong> from the Project Domains page.</Caption>

#### Subdomains

You can configure subdomains either through the **Nameservers** or **CNAME** methods.

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/configure-subdomain.png`}
  width={1350 / 2}
  height={984 / 2}
  shadow
/>
<Caption>Instructions on configuring a <strong>subdomain</strong> from the Project Domains page.</Caption>

### Step 5: Domain Configured

Once the domain has been configured, the card status will change to reflect this.

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/configured-domain.png`}
  width={1350 / 2}
  height={210 / 2}
  shadow
/>
<Caption>A configured domain on the Project Domains page.</Caption>

## Wildcard Domains

You can use your custom domain as a Wildcard Domain by prefixing it with `*.`.

<Note type="warning">
  If using your custom domain as a Wildcard Domain, you{' '}
  <b>must use the nameservers method for verification</b>.
</Note>

To add a Wildcard Domain, follow the steps to [add a domain](#step-1:-selecting-your-project), the only change being; at [step 3](#step-3:-entering-your-chosen-domain), where you should instead use the prefix mentioned above, for example; `*.acme.com`.

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/wildcard-domain.png`}
  width={1350 / 2}
  height={532 / 2}
  shadow
/>
<Caption>A <b>Wildcard Domain</b> awaiting verification.</Caption>

After the verification process is complete, the status of the domain will be updated within the UI to confirm that it is ready for use.

## Deploying with Your Domain

Once the domain has been added to your project and configured, it is **automatically applied to your latest deployment**.

<Note>
  The first deployment of a new project will be marked as production and
  subsequently assigned with your custom domain automatically.
</Note>

When a custom domain is assigned to a project with an enabled [ZEIT Now for Git integration](/docs/v2/git-integrations), each push (including merges) to the default branch (commonly `master`) will trigger a deployment to the defined domain.

Reverts take effect immediately, assigning the custom domain to the deployment made prior to the point the revert is effective from.

## Redirecting Domains

You can add domain redirects from the **Domains** tab when **more than one domain** is present for the project. This provides a way to, for example, redirect a `www` subdomain to an apex domain but can be used in a variety of ways.

To add a redirect, click the **Edit** button for the domain you want to redirect from and use the **Redirect to** dropdown to select the domain you want to redirect to:

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/redirecting-domains.png`}
  width={1398 / 2.1}
  height={642 / 2.1}
  shadow
/>
<Caption>A <b>domain redirect</b> that redirects requests made to <InlineCode>www.zeit.rocks</InlineCode> to <InlineCode>zeit.rocks</InlineCode>.</Caption>

## Moving Domains

You can move domains to another profile or team using the **Domains** tab from the **ZEIT Dashboard**.

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/select-domains-tab.png`}
  width={1224 / 2}
  height={278 / 2}
  shadow
/>
<Caption>Selecting the <b>Domains</b> tab from the ZEIT Dashboard page.</Caption>

Once on the **Domains** tab, select the domain(s) you wish to move by using the checkbox next to each domain then click **Move**.

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/domains-list.png`}
  width={1350 / 2}
  height={492 / 2}
  shadow
/>
<Caption>Selecting which domains to move from the <b>Domains</b> tab.</Caption>

After selecting the domain(s) and clicking **Move**, you will be asked to confirm which profile or team you wish to move them to.

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/move-modal.png`}
  width={840 / 2}
  height={818 / 2}
  shadow
/>
<Caption>Entering a new profile or team destination for a domain.</Caption>

When selecting the input field, you will be provided with a list of teams you belong to. If the profile or team you wish to move the domain(s) to is not present, enter the `slug` value instead. You can find the `slug` value in **Settings** page for both profiles and teams.

<Note type="warning">
  When moving domains to another team or profile, they will be removed from{' '}
  <b>all projects</b> they are currently part of.
</Note>

To confirm the change, select **Move**. The domains will be transferred to the new profile of team immediately.

## Assigning a Domain to a Git Branch

Every commit pushed to the default branch of your Git repository using our [Git integration](/docs/v2/git-integration) will be assigned the Domains [configured in your project](#adding-a-domain).

In order to automatically assign a Domain to a different branch, you can select it in the **Git Branch** dropdown of your Domain:

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/branch-domains.png`}
  width={1398 / 2.1}
  height={640 / 2.1}
  shadow
/>
<Caption>A Domain that is automatically assigned to the <InlineCode>staging</InlineCode> <b>Git Branch</b>.</Caption>

## Removing a Domain

To remove a domain that is assigned to a project, navigate to the **Domains** tab from the Project Overview and click the **Edit** button for the domain you want to remove:

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/edit-domain.png`}
  width={1400 / 2.1}
  height={218 / 2.1}
  shadow
/>
<Caption>A configured domain on the Project Domains page with the option to edit.</Caption>

Once the **Edit** button has been clicked, you will be presented with further options. Click the **Remove** button to remove the domain from the project:

<Image
  src={`${process.env.ASSETS}/docs/custom-domains/remove-domain.png`}
  width={1400 / 2.1}
  height={642 / 2.1}
  shadow
/>
<Caption>A configured domain on the Project Domains page with the option to remove.</Caption>

## Provider Specific Instructions

### Cloudflare

To use [Cloudflare](https://www.cloudflare.com/)-managed domains, follow these steps:

1. Configure your domain such that SSL is disabled for the path `/.well-known/**`.
2. Run `curl http://<domain>/.well-known/acme-challenge` (Replace `<domain>` with your domain. Notice that it’s `http` and not `https`).

If the above `curl` command returns an error (e.g. `{"error":{...}}`), then you’re good to go - it means that ZEIT can generate certificates successfully. Otherwise, make sure that SSL is disabled for `/.well-known/**` and try again.

## Related

For more information on what to do next, we recommend the following article:

<Card
  title="Transferring Your Domain"
  href="/guides/transferring-domains-to-zeit-now"
>
  Learn how to transfer a domain to ZEIT Now.
</Card>

<Card
  title="Serverless Functions"
  href="/docs/v2/serverless-functions/introduction"
>
  Extend the capabilities of your project by adding Serverless Functions to it.
</Card>

export default ({ children }) => <Doc meta={meta}>{children}</Doc>

export const config = {
  amp: 'hybrid'
}
